home *** CD-ROM | disk | FTP | other *** search
/ Megahits 3 / Megahits 3 (1994)(GTI - Rhein-Main-Soft)(DE)[!].iso / module / utilities / archives / musicxstuff.lha / RexxEdit.doc < prev   
Text File  |  1990-08-04  |  11KB  |  259 lines
  1.     RexxEdit Module for Music-X - ©1990 MicroIllusions, Inc.
  2.  
  3. Introduction:
  4.     "RexxEdit" is a module that allows Music-X to call an ARexx macro
  5. program, which can in turn edit the events in a sequence. This module only
  6. works in the Editor pages (the Bar and Event Editor). The module will attempt
  7. to start-up the ARexx server, "RexxMast," if it is not already activated.
  8.     When RexxEdit module is selected from the Module Menu, a file requester
  9. will open so the user can select an ARexx program to run. The module first
  10. looks for the logical assign "MXRexx:" and, if found, shows the contents of
  11. that drawer. If "MXRexx:" is not found, the logical assign "Rexx:" (where all
  12. standard ARexx programs are kept) will be searched for and, if found,
  13. displayed. If "Rexx:" cannot be found, then the contents of Music-X's own
  14. drawer will be displayed.
  15.     After selecting the ARexx program from the file requester and clicking on
  16. "OK", the module will run the ARexx program. The ARexx program can access the
  17. events in the currently displayed sequence by calling "external functions"
  18. that are contained within the RexxEdit module. These functions can be used to
  19. scan through the events; insert, delete or change events; or get information
  20. about the current Bar Editor enviroment. In addition, the ARexx program can
  21. create a module requester with buttons, sliders, etc., and then discover what
  22. setting the user chose.
  23.     When the ARexx program terminates, whether through normal execution or
  24. because of an error, the module will exit and return control to Music-X. Any
  25. changes made be the ARexx program will then be displayed.
  26.  
  27. Writting an ARexx Program for Editing:
  28.     First, RexxEdit always returns results from any function call, so the
  29. line "options results" must appear near the beginning of the ARexx program.
  30. RexxEdit uses the "Rexx Variable Interface" for editing events, which means
  31. that RexxEdit communcates information about events by directly reading or
  32. changing variables in the ARexx program. The most important of these
  33. variables are those with the stem "EVENT".
  34.     To begin editing a sequence, the function BEGINSCAN must be called with a
  35. parameter indicating whether "all" or just "selected" events are being
  36. scanned for. When done editing a sequence, the program must call ENDSCAN. (If
  37. a program terminates by error during an editing section, a default ENDSCAN
  38. will be performed.)
  39.     To get each event in the sequence, the program must call NEXTEVENT. This
  40. will cause a number of variables with the stem "EVENT" to be created or
  41. filled-in. For instance, a control change event would have the variables
  42. EVENT.TYPE, EVENT.CHANNEL, EVENT.NUM, EVENT.VALUE, EVENT.START.BARS,
  43. EVENT.START.CLOCKS, etc., set to the values contained in the event in the
  44. sequence. There is a table below which gives all the possible variables for
  45. each event type.
  46.     The program could then change these values and replace the event by
  47. calling REPLEVENT. Or it could change the values and ask that this be
  48. inserted as a new event with ADDEVENT. Or the event could just be deleted by
  49. calling REMEVENT. If the program wanted to quickly copy the event to another
  50. stem variable, it could call COPYEVENT with the name of the stem.
  51.     RexxEdit also allows the program to peek ahead to look at other events by
  52. calling PEEKEVENT with stem variable to return the result in and the number
  53. of events to peek ahead. Note that the peek-ahead event cannot be editted
  54. (although this may change in a future release of RexxEdit).
  55.  
  56. User Interface Functions:
  57.     Unless the ARexx program only does some simple action (like remove all
  58. events after an END event), it is likely that the program will need some
  59. input from the user. This is provided by the "algoritmic module requester
  60. design functions" -- quite a name, huh? The program first defines the type of
  61. controls it desires in the requester and then calls MXREQUEST with the name
  62. of the requester and an optional name for the "PROCEED" button. The following
  63. types of controls are available in this release:
  64.     MXBUTTON - A toggle button with a label to the right of it.
  65.     MXRADIO - A set of mutually exclusive buttons with labels next to them.
  66.     MXSLIDER - A slider with a label to the left of it. The minimum and
  67. maximum values are given as paramters. The minimum value must be positive or
  68. zero and cannot be greater than 255.
  69.     MXMIRROR - Another slider which goes from a negative to positive value.
  70.     MXNOTESIZE - Puts up one of those note size selection gadgets (like the
  71. Grid Requester has), including a slider and a label to the left of the
  72. slider.
  73.     So, to create a requester with a slider asking for a note transposition
  74. value, a radio button set to chose selected or all events, and having an
  75. alternate name to PROCEED control of "TRANSPOSE", the program would do as
  76. follows (/* ... */ being comments):
  77.  
  78.     MXMIRROR "Note Value:,127"                /* -127 to 127 */
  79.     MXRADIO "Selected events,All events"
  80.     MXREQUEST "TRANSPOSE NOTES,TRANSPOSE"
  81.  
  82.     When MXREQUEST returns, the program can query the button and slider
  83. settings by calling MXVALUE with the number of the control (starting at
  84. zero). In the above example the MXMIRROR slider would be control 0, while the
  85. MXRADIO set would be control 1. The value is returned in the global ARexx
  86. variable "RESULT".
  87.     In addition to the button layout functions, the program can put up a
  88. message at any time be calling MXREPORT. The program can also change the
  89. pointer (to indicate the program is busy) by calling MXPOINTER with either
  90. the parameter "sleepy" or "normal".
  91.  
  92.  
  93. (A Short) Summary of Functions:
  94.  
  95. Event Editing:
  96.  
  97. BEGINSCAN 'mode'
  98.     Starts an event scan. 'mode' is either 'all' or 'selected'.
  99.     Returns 1 if the scan started properly, returns 0 on an error.
  100.  
  101. ENDSCAN
  102.     End a scan. Must be called before starting a new scan or when exiting
  103. from execution.
  104.  
  105. NEXTEVENT
  106.     Read the next event into the stem variable "EVENT". Returns 1 if
  107. everything went well, returns 0 if something went wrong or there are no more
  108. events.
  109.  
  110. PEEKEVENT 'stem[,count]'
  111.     Peek ahead by 'count' events (defaults to 1) and place the resulting
  112. information in the variable 'stem'. Returns either 1 (success) or 0
  113. (failure).
  114.  
  115. ADDEVENT
  116.     Uses the values in the stem variable "EVENT" to create a new event and
  117. add it to the sequence. Returns either 1 (success) or 0 (failure).
  118.  
  119. REMEVENT
  120.     Removes the current event. Returns either 1 (success) or 0 (failure).
  121.  
  122. REPLEVENT
  123.     Uses the values in the stem variable "EVENT" to replace the values in the
  124. current event. Returns either 1 (success) or 0 (failure).
  125.  
  126. COPYEVENT 'stem'
  127.     Copies the values in variable "EVENT" to the variable 'stem'. Returns
  128. either 1 (success) or 0 (failure).
  129.  
  130. Requester and Control Handling:
  131.  
  132. MXBUTTON 'label'
  133.     Creates a toggle button with 'label' printed to the right. Returns either
  134. 1 (success) or 0 (could not create control).
  135. MXRADIO 'label1,label2,...'
  136.     Creates a set of mutually exclusive buttons (maximum of 5 in the set)
  137. with 'label1,label2,...' printed to the right of each button. Returns either
  138. 1 (success) or 0 (could not create control).
  139.  
  140. MXSLIDER 'label,minval,maxval'
  141.     Creates a slider with 'minval' and 'maxval'. 'minval' must be positive or
  142. zero and cannot be greater than 255. 'label' is printed to the left of the
  143. slider. Returns either 1 (success) or 0 (could not create control).
  144.  
  145. MXMIRROR 'label,maxval'
  146.     Creates a slider whose maximum value is 'maxval' and minimum is negative
  147. 'maxval'. 'label' is printed to the left of the slider. Returns either 1
  148. (success) or 0 (could not create control).
  149.  
  150. MXNOTESIZE 'label'
  151.     Creates a set of note selection controls (including a slider) like the
  152. ones in the Grid Requester. 'label' is printed to the left of the slider.
  153. Returns either 1 (success) or 0 (could not create control).
  154.  
  155. MXREQUEST 'title[,proceed]'
  156.     Put up a requester containing all previously defined controls, plus
  157. PROCEED and CANCEL controls. The requester will have be labeled 'title'.
  158. Optionally, the PROCEED control can be relabeled. Returns 1 if the user
  159. wanted to proceed, 0 if the user wanted to cancel.
  160.  
  161. MXVALUE which
  162.     Returns the final value of control 'which'. For a MXBUTTON, the value is
  163. 0 if the control was unselected and 1 if selected. For a MXRADIO, the value
  164. if the button hilites with the first button being 0, the second 1, etc. For
  165. MXSLIDER, MXMIRROR and MXNOTESIZE controls, returns the slider setting.
  166.  
  167. Other Functions:
  168.  
  169. MXREPORT 'message1[,message2]'
  170.     Put up a message box where the first line is 'message1' and the optional
  171. second line is 'message 2'.
  172.  
  173. MXPOINTER 'mode'
  174.     Change the Music-X pointer to either 'normal' mode or 'sleepy' mode.
  175.  
  176. GETBARDATA
  177.     Put the values of the current grid and step size in the Bar editor into
  178. the variables BARDATA.GRID and BARDATA.STEP, respectfully.
  179.  
  180. Variables Returned by NEXTEVENT:
  181.     All events have an EVENT.TYPE, which is a string. If the sequence uses
  182. relative time, the variable EVENT.CLOCKTYPE will be set to 'REL' and the
  183. variables EVENT.START.BARS and EVENT.START.CLOCKS will contain the event's
  184. measure and ticks in measure start times, while EVENT.START.TICKS will
  185. contain the total number of ticks from the start of the sequence. Absolute
  186. sequences will have a EVENT.CLOCKTYPE of 'ABS' and have the variable
  187. EVENT.START.QFRAMES which contains the event's start time in quarter-frames.
  188. If the event also has a stop time, additional time vaiables will be defined
  189. as above except with START replaced by STOP. If the event has a channel
  190. assignment, EVENT.CHANNEL will be defined. All other variables vary by event
  191. type as note in the list below.
  192.  
  193. Event types and variables:
  194.  
  195.     'END'  - an END event
  196.         (no extra variables)
  197.  
  198.     'STOP' - a stop sequence event
  199.         (no extra variables)
  200.  
  201.     'REPT' - a repeat count
  202.         EVENT.NUM - the number of repeats
  203.  
  204.     'TSIG' - a time signature change
  205.         EVENT.NUM - the numerator of the time signature
  206.         EVENT.DEM - the denominator of the time signature as a power of two
  207.  
  208.     'KMAP' - keymap change
  209.         EVENT.MAP - number of the keymap
  210.  
  211.     'SYSX' - real-time system exclusive
  212.        EVENT.NUM - number of bytes of data in this event
  213.        EVENT.DATA - a packed string of the data
  214.        EVENT.LAST - 0 if this is not the last event for this SYSX packet
  215.                     1 if this is the last event in the packet
  216.  
  217.     'PSEQ' - play sequence event
  218.         EVENT.NUM - number of the sequence to play
  219.         EVENT.TRANSPOSE - transposition value
  220.         EVENT.CUT - cut value
  221.  
  222.     'TEMP' - tempo change
  223.         EVENT.NUM - new tempo value
  224.  
  225.     'MSEQ' - mute sequence
  226.         EVENT.NUM - sequence to mute
  227.  
  228.     'SSEQ' - solo sequence
  229.         EVENT.NUM - sequence to solo
  230.  
  231.     'MTRK' - mute track
  232.         EVENT.NUM - track to mute
  233.  
  234.     'STRK' - solo track
  235.         EVENT.NUM - track to solo
  236.  
  237.     'NOTE' - note event
  238.         EVENT.NUM - midi note number
  239.         EVENT.ATTACK - attack velocity
  240.         EVENT.RELEASE - release velocity
  241.  
  242.     'PAT' - polyphonic aftertouch
  243.         EVENT.NUM - note number
  244.         EVENT.PRESSURE - new pressure
  245.  
  246.     'CTL' - control change
  247.         EVENT.NUM - controller number
  248.         EVENT.VALUE - new value
  249.  
  250.     'PGM' - program change
  251.         EVENT.NUM - program number
  252.  
  253.     'CAT' - channel aftertouch
  254.         EVENT.PRESSURE - new presssure value
  255.  
  256.     'PBEN' - pitch bend
  257.         EVENT.NUM - pitch bend value
  258.  
  259.